---
title: Configure Port-Forwarding
sidebar_label: ports[].forward
---

import FragmentImageSelector from '../../fragments/selector-image-selector.mdx';
import FragmentLabelSelector from '../../fragments/selector-label-selector.mdx';


Port-forwarding allows you to access your application on `localhost:[PORT]` by forwarding the network traffic from a localhost port to a specified port of a container.

When starting the development mode, DevSpace starts port-forwarding as configured in the `dev.ports` section of the `devspace.yaml`.
```yaml {15-19}
images:
  backend:
    image: john/devbackend
  backend-debugger:
    image: john/debugger
deployments:
- name: app-backend
  helm:
    componentChart: true
    values:
      containers:
      - image: john/devbackend
      - image: john/debugger
dev:
  ports:
  - imageSelector: john/devbackend
    forward:
    - port: 8080
      remotePort: 80
```

:::warning Unique Local Port
The `port` option must be unique across your entire `ports` section, e.g. you can only use the value `8080` once for the `port` option in your `ports` section.
:::

Every port-forwarding configuration consists of two parts:
- [Pod/Container Selection](#pod-selection)
- [Port Mapping via `port` (and optionally via `remotePort` and `bindAddress`)](#port-mapping-forward)

## Configuration

### `name`
The `name` option is optional and expects a string stating the name of this port-forwarding configuration. This can be used as a steady identifier when using profile patches or to override the log message prefix for this port configuration.

For example:
```yaml {3}
dev:
  ports:
  - name: devbackend
    imageSelector: john/devbackend
    forward:
    - port: 8080
      remotePort: 80
profiles:
- name: production
  patches:
  - op: replace
    path: dev.ports.name=devbackend.imageSelector
    value: john/prodbackend
```

## Pod Selection
The following config options are needed to determine the pod to which the traffic should be forwarded:
- [`imageSelector`](#imageselector)
- [`labelSelector`](#labelselector)
- [`namespace`](#namespace)

:::info Combine Options
If you specify multiple of these config options, they will be jointly used to select the pod / container (think logical `AND / &&`).
:::

:::info Auto Reconnect
If DevSpace is unable to establish a port-forwarding connection to the selected pod or loses it after starting the port-forwarding, DevSpace will try to restart port-forwarding several times.
:::

### `imageSelector`
<FragmentImageSelector/>

#### Example: Select Pod by Image Name
```yaml {2,4,18,22}
images:
  backend:
    image: john/devbackend
  backend-debugger:
    image: john/debugger
deployments:
- name: app-backend
  helm:
    componentChart: true
    values:
      containers:
      - name: container-0
        image: john/devbackend
      - name: container-1
        image: john/debugger
dev:
  ports:
  - imageSelector: john/devbackend
    forward:
    - port: 8080
      remotePort: 80
  - imageSelector: john/debugger
    forward:
    - port: 3000
```
**Explanation:**
- The above example defines two images that can be used as `imageSelector`: `john/devbackend` and `john/debugger`
- The deployment starts two containers and each of them uses an image from the `images` section.
- The `imageName` option of the first port-forwarding configuration in the `dev.ports` section references `backend`. That means DevSpace would select the first container for port-forwarding, as this container uses the `image: john/devbackend` which belongs to the `backend` image as defined in the `images` section.
- The `imageName` option of the second port-forwarding configuration in the `dev.ports` section references `backend-debugger`. That means DevSpace would select the second container for port-forwarding, as this container uses the `image: john/debugger` which belongs to the `backend-debugger` image as defined in the `images` section.

In consequence, the following port-forwarding processes would be started when using the above config example:
- `localhost:8080` forwards to `container-0:80`
- `localhost:3000` forwards to `container-1:3000`


### `labelSelector`
<FragmentLabelSelector />

#### Example: Select Pod by Label
```yaml {18-21}
images:
  backend:
    image: john/devbackend
  backend-debugger:
    image: john/debugger
deployments:
- name: app-backend
  helm:
    componentChart: true
    values:
      containers:
      - name: container-0
        image: john/devbackend
      - name: container-1
        image: john/debugger
dev:
  ports:
  - labelSelector:
      app.kubernetes.io/name: devspace-app
      app.kubernetes.io/component: app-backend
      custom-label: custom-label-value
    forward:
    - port: 8080
      remotePort: 80
```
**Explanation:**
- The `labelSelector` would select the pod created for the component deployment `app-backend`.
- Because containers in the same pod share the same network stack, we do not need to specify which container should be selected.


### `namespace`
The `namespace` option expects a string with a Kubernetes namespace used to select the pod from.

:::warning
It is generally **not** needed (nor recommended) to specify the `namespace` option because, by default, DevSpace uses the default namespace of your current kube-context which is usually the one that has been used to deploy your containers to.
:::

## Port Mapping `forward`
The `forward` section defines which localhost `port` should be forwarded to the `remotePort` of the selected container.

:::note
By default, `remotePort` will take the same value as `port` if `remotePort` is not explicitly defined.
:::

### `port`
The `port` option is mandatory and expects an integer from the range of user ports [1024 - 49151].

:::warning
Using a `port` < 1024 is likely to cause problems as these ports are reserved as system ports.
:::

#### Example
**See "[Example: Select Pod by Image Name](#example-select-pod-by-image-name)"**


### `remotePort`
The `remotePort` option expects an integer from the range of valid ports [0 - 65535].

:::info
By default, `remotePort` has the same value as `port` if `remotePort` is not explictly defined.
:::

#### Example
**See "[Example: Select Pod by Image Name](#example-select-pod-by-image-name)"**


### `bindAddress`
The `bindAddress` option expects a valid IP address that the local port should be bound to.

#### Default Value For `bindAddress`
```yaml
bindAddress: "localhost" # listen on all network interfaces
```
